Scripting
文档
更新日志
隐私
文档
更新日志
隐私
简体中文

通知

Scripting App 中的 Notification 模块用于安排、管理和展示本地通知，支持多种触发方式、交互操作按钮和富交互界面（自定义 UI）。

目录

  1. 安排通知

  2. 通知触发器

  3. 通知操作按钮

  4. 富通知（自定义 UI）

  5. 通知管理

  6. 通知信息与请求结构

  7. 完整示例

安排通知

使用 Notification.schedule 来安排本地通知。它支持标题、触发器、点击行为、操作按钮、自定义 UI 和其他投递选项：

1await Notification.schedule({
2  title: "提醒事项",
3  body: "该起身活动了！",
4  trigger: new TimeIntervalNotificationTrigger({
5    timeInterval: 1800,
6    repeats: true
7  }),
8  actions: [
9    {
10      title: "我知道了",
11      icon: "checkmark",
12      url: Script.createRunURLScheme("确认脚本", { acknowledged: true })
13    }
14  ],
15  tapAction: {
16    type: "runScript",
17    scriptName: "确认脚本"
18  },
19  customUI: false
20})

参数说明

参数名 类型 说明
title string 必填，通知标题。
subtitle string? 可选，副标题内容。
body string? 可选，正文内容。
iconImageData Data | SystemImageIcon | null 可选，自定义通知图标图片的二进制数据或系统图标名称。
badge number? 可选，应用图标角标数字。
silent boolean? 可选，默认为 false。设为 true 则不播放声音静默送达。
interruptionLevel "active" | "passive" | "timeSensitive" 可选，通知的重要级别和投递优先级。
userInfo Record<string, any>? 可选，附加的自定义数据。
threadIdentifier string? 可选，用于通知分组的标识符。
trigger TimeIntervalNotificationTrigger | CalendarNotificationTrigger | LocationNotificationTrigger | null 可选，定义何时发送通知。
actions NotificationAction[]? 可选，通知展开后展示的操作按钮。
customUI boolean? 可选，设为 true 可使用 notification.tsx 自定义 UI。
tapAction "none" | { type: "runScript", scriptName: string } | { type: "openURL", url: string } 可选，定义用户点击通知时执行的操作。

SystemImageIcon

1type SystemImageIcon = {
2  systemImage: string
3  color: Color
4}

用于定义通知图标的系统图标名称和颜色。

  • systemImage: 系统图标（SFSymbol）名称

  • color: 图标颜色

通知操作按钮（actions）

通过 actions 参数，你可以为通知添加操作按钮。操作按钮会在通知展开后出现，用户可以点击进行操作。

通知操作按钮类型（NotificationAction）

1type NotificationAction = {
2    title: string;
3    icon?: string;
4    url: string;
5    destructive?: boolean;
6}
  • title: 按钮标题
  • icon: 按钮图标
  • url: 点击后打开的 URL
  • destructive: 是否为破坏性操作

点击行为（tapAction）

通过 tapAction 参数，你可以完全控制用户点击通知时的行为：

  • "none"：点击后无任何响应
  • { type: "runScript", scriptName: string }：运行指定脚本
  • { type: "openURL", url: string }：打开指定 URL，可为 deeplink 或 https 链接

如果不设置 tapAction，默认行为是运行当前脚本，你可以通过 Notification.current 获取通知内容。

通知触发器

TimeIntervalNotificationTrigger

在指定秒数后触发通知：

1new TimeIntervalNotificationTrigger({
2  timeInterval: 3600,
3  repeats: true
4})
  • timeInterval: 延迟秒数
  • repeats: 是否重复触发
  • nextTriggerDate(): 返回下次预期触发的时间

CalendarNotificationTrigger

根据特定日期和时间触发通知：

1const components = new DateComponents({ hour: 8, minute: 0 })
2new CalendarNotificationTrigger({
3  dateMatching: components,
4  repeats: true
5})
  • 支持设置 year、month、day、hour 等
  • 适用于每日、每周或特定时间提醒

LocationNotificationTrigger

当进入或离开某个地理区域时触发：

1new LocationNotificationTrigger({
2  region: {
3    identifier: "公司",
4    center: { latitude: 37.7749, longitude: -122.4194 },
5    radius: 100,
6    notifyOnEntry: true,
7    notifyOnExit: false
8  },
9  repeats: false
10})
  • 支持进入/离开圆形区域的触发

通知操作按钮

通过 actions 参数添加通知操作按钮：

1actions: [
2  {
3    title: "查看详情",
4    url: Script.createRunURLScheme("详情脚本", { fromNotification: true })
5  },
6  {
7    title: "忽略",
8    url: Script.createRunURLScheme("忽略脚本", { dismissed: true }),
9    destructive: true
10  }
11]
  • 使用 Script.createRunURLScheme(...) 创建 URL
  • 按钮在长按或下拉通知时显示

富通知（自定义 UI）

你可以使用 TSX 文件定义通知的展开视图：

  1. 安排通知时设置 customUI: true
  2. 在脚本中添加 notification.tsx 文件
  3. 使用 Notification.present(<JSX>) 渲染 UI

Notification.present(element: JSX.Element): void

在 notification.tsx 中调用，用于渲染富通知界面。

示例 notification.tsx

1import { Notification, VStack, Text, Button } from 'scripting'
2
3function NotificationView() {
4  return (
5    <VStack>
6      <Text>需要完成你的任务吗？</Text>
7      <Button title="已完成" action={() => console.log("任务完成")} />
8      <Button title="稍后提醒" action={() => console.log("稍后提醒")} />
9    </VStack>
10  )
11}
12
13Notification.present(<NotificationView />)

通知管理

方法名 说明
getAllDelivereds() 获取所有已送达的通知
getAllPendings() 获取所有已安排但尚未送达的通知
removeAllDelivereds() 移除所有已送达的通知
removeAllPendings() 取消所有待发送通知
removeDelivereds(ids) 移除指定 ID 的已送达通知
removePendings(ids) 取消指定 ID 的已安排通知
getAllDeliveredsOfCurrentScript() 获取当前脚本发送的已送达通知
getAllPendingsOfCurrentScript() 获取当前脚本安排的待发送通知
removeAllDeliveredsOfCurrentScript() 清除当前脚本的所有已送达通知
removeAllPendingsOfCurrentScript() 清除当前脚本的所有待发送通知
setBadgeCount(count) 设置应用图标的角标数值

通知信息与请求结构

当脚本是通过点击通知启动时，可以通过 Notification.current 获取上下文信息：

1if (Notification.current) {
2  const { title, userInfo } = Notification.current.request.content
3  console.log(`从通知启动：${title}`, userInfo)
4}

NotificationRequest 字段

字段名 说明
identifier 通知请求的唯一标识符
content.title 通知标题
content.subtitle 通知副标题
content.body 通知正文
content.userInfo 附加信息
content.threadIdentifier 分组标识
trigger 触发器对象，控制通知的投递逻辑

完整示例

以下示例展示了通知的完整用法：自定义 UI、交互按钮、点击行为、重复触发等。

第一步：安排通知

1await Notification.schedule({
2  title: "喝水提醒",
3  body: "别忘了喝水哦！",
4  interruptionLevel: "timeSensitive",
5  iconImageData: UIImage
6    .fromSFSymbol("waterbottle")!
7    .withTintColor("systemBlue")!
8    .toPNGData(),
9  customUI: true,
10  trigger: new TimeIntervalNotificationTrigger({
11    timeInterval: 3600,
12    repeats: true
13  }),
14  tapAction: {
15    type: "runScript",
16    scriptName: "喝水记录"
17  },
18  actions: [
19    {
20      title: "已喝水",
21      url: Script.createRunURLScheme("喝水记录", { drank: true }),
22    },
23    {
24      title: "忽略",
25      url: Script.createRunURLScheme("喝水记录", { drank: false }),
26      destructive: true
27    }
28  ]
29})

第二步：创建 notification.tsx

1import { Notification, VStack, Text, Button } from 'scripting'
2
3function HydrationUI() {
4  return (
5    <VStack>
6      <Text>你刚刚喝水了吗？</Text>
7      <Button title="是的" action={() => console.log("已确认喝水")} />
8      <Button title="还没" action={() => console.log("忽略提醒")} />
9    </VStack>
10  )
11}
12
13Notification.present(<HydrationUI />)

总结

Scripting 中的 Notification API 提供了强大的本地通知功能：

  • 支持时间、日历、位置触发器
  • 支持操作按钮及跳转脚本
  • 通过 tapAction 自定义点击通知的行为
  • 使用 notification.tsx 创建富交互通知界面
  • 提供全面的通知生命周期管理
大纲